@cyphra/graphql 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -2
- package/dist/index.d.ts +159 -15
- package/dist/index.js +2572 -597
- package/dist/index.js.map +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -28,9 +28,33 @@ Status (early release):
|
|
|
28
28
|
- Mutations: `create`, `update`, `delete` with `info` counters, nested `create` / `connect` /
|
|
29
29
|
`disconnect` / `update` / `delete` with edge properties, every update operator (deprecated forms
|
|
30
30
|
included), `@id`, `@timestamp` and `@default`. No APOC needed.
|
|
31
|
+
- `@authentication` / `@authorization` (type, field and `extend schema` level), `@jwt` and
|
|
32
|
+
`@jwtClaim`: rules are compiled into the Cypher statement (filters in its `WHERE`, `validate`
|
|
33
|
+
checks inside it, a failed check rolls the statement back), never applied in JavaScript.
|
|
34
|
+
- `@cypher` fields on node types, relationship properties, `Query` and `Mutation`: scalar and
|
|
35
|
+
node results, arguments (always passed as parameters), `this`, `$jwt`, `where` and `sort` on
|
|
36
|
+
scalar fields, filters on node results, the READ rules of returned nodes.
|
|
37
|
+
- `@fulltext` queries (`score`, `where`, `sort`, `first` / `after`) on full-text indexes you
|
|
38
|
+
create, as in v7.
|
|
31
39
|
- One Cypher statement per root field, in its own transaction. Needs Neo4j 5.23+.
|
|
32
|
-
- Not yet: `@
|
|
33
|
-
|
|
40
|
+
- Not yet: interfaces, unions, subscriptions, `@vector`, `Point` / `Duration` and custom scalars
|
|
41
|
+
(`makeSchema` throws `UnsupportedTypeDefsError`).
|
|
42
|
+
|
|
43
|
+
JWTs are verified like v7, with `features.authorization` and the request's `Authorization` header
|
|
44
|
+
as `token` in the context (a decoded `jwt` in the context is trusted as it is):
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
const schema = compat.v7.makeSchema({
|
|
48
|
+
typeDefs,
|
|
49
|
+
driver,
|
|
50
|
+
features: { authorization: { key: process.env.JWT_SECRET! } }, // or { key: { url: jwksUrl } }
|
|
51
|
+
});
|
|
52
|
+
// GraphQL server context: ({ request }) => ({ token: request.headers.get("authorization") })
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Read the [authorization docs](https://www.cyphra.dev/graphql#authentication-and-authorization) for
|
|
56
|
+
the v7 behaviours that matter for security (filters on fields the user cannot read, AGGREGATE vs
|
|
57
|
+
READ rules, relationship-only updates) and the few cases where Cyphra is stricter than v7.
|
|
34
58
|
|
|
35
59
|
Compatibility is measured against the real `@neo4j/graphql` by the suite in
|
|
36
60
|
[`compat/graphql`](https://github.com/Cyphra-dev/cyphra/tree/main/compat/graphql).
|
package/dist/index.d.ts
CHANGED
|
@@ -2,13 +2,14 @@ import { ConstValueNode, GraphQLSchema } from 'graphql';
|
|
|
2
2
|
import { SchemaDocument, SchemaModel } from '@cyphra/schema';
|
|
3
3
|
import { CyphraClient } from '@cyphra/runtime';
|
|
4
4
|
import { Driver } from 'neo4j-driver';
|
|
5
|
+
import { RemoteJWKSetOptions, JWTVerifyOptions } from 'jose';
|
|
5
6
|
|
|
6
7
|
/**
|
|
7
8
|
* The mapping from `@neo4j/graphql` v7 type definitions to Cyphra, in one place.
|
|
8
9
|
*
|
|
9
10
|
* Each GraphQL scalar, type-level directive and field-level directive has one entry here. When
|
|
10
|
-
* Cyphra gains a feature (
|
|
11
|
-
*
|
|
11
|
+
* Cyphra gains a feature (`Point`, `Duration`, …), supporting it in the importer means changing
|
|
12
|
+
* that entry: the converter in `convert.ts` only walks the SDL and applies these rules.
|
|
12
13
|
*
|
|
13
14
|
* Semantics follow `@neo4j/graphql` 7.x (checked against 7.6.8):
|
|
14
15
|
* - only object types with `@node` are nodes; `@node(labels)` sets the Neo4j labels;
|
|
@@ -122,6 +123,37 @@ type ExecutorOptions = {
|
|
|
122
123
|
debug?: boolean;
|
|
123
124
|
};
|
|
124
125
|
|
|
126
|
+
/**
|
|
127
|
+
* JWT verification for `@authentication` / `@authorization`, configured like `@neo4j/graphql` v7
|
|
128
|
+
* (`features.authorization`): the bearer token of the request (`context.token`) is verified with
|
|
129
|
+
* `jose` against a symmetric secret or a JWKS endpoint. A token that is missing, malformed, expired,
|
|
130
|
+
* not yet valid or signed with another key leaves the request unauthenticated (no error), like v7.
|
|
131
|
+
*
|
|
132
|
+
* @packageDocumentation
|
|
133
|
+
*/
|
|
134
|
+
|
|
135
|
+
type AnyRecord$1 = Record<string, unknown>;
|
|
136
|
+
/** A symmetric secret (HS256 / HS384 / HS512), or the URL of a JWKS endpoint. */
|
|
137
|
+
type JwtKey = string | {
|
|
138
|
+
url: string;
|
|
139
|
+
options?: RemoteJWKSetOptions;
|
|
140
|
+
};
|
|
141
|
+
/** `features.authorization` of `Neo4jGraphQL`: how tokens are verified. */
|
|
142
|
+
type AuthorizationFeature = {
|
|
143
|
+
/** The key, or a function of the GraphQL context returning it (per request). */
|
|
144
|
+
key: JwtKey | ((context: AnyRecord$1) => JwtKey);
|
|
145
|
+
/**
|
|
146
|
+
* `false` decodes tokens without verifying the signature (v7 option). Only for tokens already
|
|
147
|
+
* verified upstream (e.g. by a gateway): anyone can forge an unverified token.
|
|
148
|
+
*/
|
|
149
|
+
verify?: boolean;
|
|
150
|
+
/** Passed to `jose`'s `jwtVerify` (`issuer`, `audience`, `algorithms`, `clockTolerance`, …). */
|
|
151
|
+
verifyOptions?: JWTVerifyOptions;
|
|
152
|
+
};
|
|
153
|
+
type Features = {
|
|
154
|
+
authorization?: AuthorizationFeature;
|
|
155
|
+
};
|
|
156
|
+
|
|
125
157
|
/**
|
|
126
158
|
* The `@neo4j/graphql` v7 type definitions, read into the model the v7 API is generated from.
|
|
127
159
|
*
|
|
@@ -145,6 +177,51 @@ type CypherAnnotation = {
|
|
|
145
177
|
readonly statement: string;
|
|
146
178
|
readonly columnName: string;
|
|
147
179
|
};
|
|
180
|
+
/** An argument of a `@cypher` field (scalar or enum, list or not), e.g. `tags(prefix: String = "x")`. */
|
|
181
|
+
type FieldArgument = {
|
|
182
|
+
readonly name: string;
|
|
183
|
+
readonly type: TypeRef;
|
|
184
|
+
readonly kind: "scalar" | "enum";
|
|
185
|
+
readonly description?: string;
|
|
186
|
+
/** The raw default value AST, printed in the SDL and applied by GraphQL. */
|
|
187
|
+
readonly defaultAst?: ConstValueNode;
|
|
188
|
+
};
|
|
189
|
+
/** A `@cypher` field of a node type returning nodes (`[Person!]!` or `Person`). */
|
|
190
|
+
type CypherNodeField = {
|
|
191
|
+
readonly name: string;
|
|
192
|
+
/** Node type of the returned nodes. */
|
|
193
|
+
readonly target: string;
|
|
194
|
+
readonly type: TypeRef;
|
|
195
|
+
readonly cypher: CypherAnnotation;
|
|
196
|
+
readonly args: readonly FieldArgument[];
|
|
197
|
+
readonly description?: string;
|
|
198
|
+
readonly deprecated?: string;
|
|
199
|
+
};
|
|
200
|
+
/** A `@cypher` field of `Query` or `Mutation`. */
|
|
201
|
+
type CypherRootField = {
|
|
202
|
+
readonly name: string;
|
|
203
|
+
readonly type: TypeRef;
|
|
204
|
+
/** `node` when the named type is a `@node` type. */
|
|
205
|
+
readonly kind: "scalar" | "enum" | "node";
|
|
206
|
+
readonly cypher: CypherAnnotation;
|
|
207
|
+
readonly args: readonly FieldArgument[];
|
|
208
|
+
readonly description?: string;
|
|
209
|
+
readonly deprecated?: string;
|
|
210
|
+
/** Field-level `@authentication`. */
|
|
211
|
+
readonly authentication?: AuthenticationAnnotation;
|
|
212
|
+
};
|
|
213
|
+
/** The custom fields of `Query` or `Mutation`, with the type-level `@authentication`. */
|
|
214
|
+
type CypherRootType = {
|
|
215
|
+
readonly fields: readonly CypherRootField[];
|
|
216
|
+
readonly authentication?: AuthenticationAnnotation;
|
|
217
|
+
};
|
|
218
|
+
/** One index of `@fulltext(indexes: [{ indexName, queryName, fields }])`. */
|
|
219
|
+
type FulltextIndex = {
|
|
220
|
+
readonly indexName: string;
|
|
221
|
+
/** Root query field, e.g. `moviesByTitle`. */
|
|
222
|
+
readonly queryName: string;
|
|
223
|
+
readonly fields: readonly string[];
|
|
224
|
+
};
|
|
148
225
|
type Attribute = {
|
|
149
226
|
readonly name: string;
|
|
150
227
|
/** Property key in Neo4j (`@alias(property)`), defaults to the field name. */
|
|
@@ -161,8 +238,12 @@ type Attribute = {
|
|
|
161
238
|
/** `@timestamp(operations)`. */
|
|
162
239
|
readonly timestamp?: readonly ("CREATE" | "UPDATE")[];
|
|
163
240
|
readonly cypher?: CypherAnnotation;
|
|
241
|
+
/** Arguments of a `@cypher` field (other fields have none). */
|
|
242
|
+
readonly args: readonly FieldArgument[];
|
|
164
243
|
/** User `@deprecated(reason)` on the field. */
|
|
165
244
|
readonly deprecated?: string;
|
|
245
|
+
/** Field-level `@authentication` / `@authorization`. */
|
|
246
|
+
readonly auth?: AuthAnnotations;
|
|
166
247
|
};
|
|
167
248
|
type Relationship = {
|
|
168
249
|
readonly name: string;
|
|
@@ -178,11 +259,37 @@ type Relationship = {
|
|
|
178
259
|
readonly description?: string;
|
|
179
260
|
readonly deprecated?: string;
|
|
180
261
|
};
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
262
|
+
/** Operations `@authentication` / `@authorization` rules apply to. */
|
|
263
|
+
declare const AUTH_OPERATIONS: readonly ["READ", "AGGREGATE", "CREATE", "UPDATE", "DELETE", "CREATE_RELATIONSHIP", "DELETE_RELATIONSHIP", "SUBSCRIBE"];
|
|
264
|
+
type AuthOperation = (typeof AUTH_OPERATIONS)[number];
|
|
265
|
+
type AnyRecord = Record<string, unknown>;
|
|
266
|
+
/** `@authentication(operations, jwt)`. */
|
|
267
|
+
type AuthenticationAnnotation = {
|
|
268
|
+
readonly operations: ReadonlySet<AuthOperation>;
|
|
269
|
+
/** `jwt: { … }` filter the decoded JWT must match (checked in JS, before the statement runs). */
|
|
270
|
+
readonly jwt?: AnyRecord;
|
|
271
|
+
};
|
|
272
|
+
/** One `filter` rule of `@authorization`. */
|
|
273
|
+
type AuthorizationRule = {
|
|
274
|
+
readonly operations: readonly AuthOperation[];
|
|
275
|
+
/** Default `true`: the rule only holds for authenticated requests. */
|
|
276
|
+
readonly requireAuthentication: boolean;
|
|
277
|
+
/** `{ node, jwt, AND, OR, NOT }` with `$jwt.<claim>` / `$context.<path>` string references. */
|
|
278
|
+
readonly where: AnyRecord;
|
|
279
|
+
};
|
|
280
|
+
/** One `validate` rule of `@authorization`. */
|
|
281
|
+
type AuthorizationValidateRule = AuthorizationRule & {
|
|
282
|
+
/** Default both: checked before and after the write. */
|
|
283
|
+
readonly when: readonly ("BEFORE" | "AFTER")[];
|
|
284
|
+
};
|
|
285
|
+
type AuthorizationAnnotation = {
|
|
286
|
+
readonly filter: readonly AuthorizationRule[];
|
|
287
|
+
readonly validate: readonly AuthorizationValidateRule[];
|
|
288
|
+
};
|
|
289
|
+
/** `@authentication` / `@authorization` of a type or of a field. */
|
|
290
|
+
type AuthAnnotations = {
|
|
291
|
+
readonly authentication?: AuthenticationAnnotation;
|
|
292
|
+
readonly authorization?: AuthorizationAnnotation;
|
|
186
293
|
};
|
|
187
294
|
type NodeType = {
|
|
188
295
|
readonly name: string;
|
|
@@ -195,7 +302,11 @@ type NodeType = {
|
|
|
195
302
|
readonly pascalPlural: string;
|
|
196
303
|
readonly attributes: readonly Attribute[];
|
|
197
304
|
readonly relationships: readonly Relationship[];
|
|
198
|
-
|
|
305
|
+
/** `@cypher` fields returning nodes. */
|
|
306
|
+
readonly cypherNodes: readonly CypherNodeField[];
|
|
307
|
+
/** `@fulltext` indexes. */
|
|
308
|
+
readonly fulltext: readonly FulltextIndex[];
|
|
309
|
+
readonly auth: AuthAnnotations;
|
|
199
310
|
};
|
|
200
311
|
type PropertiesType = {
|
|
201
312
|
readonly name: string;
|
|
@@ -212,8 +323,18 @@ type EnumType = {
|
|
|
212
323
|
};
|
|
213
324
|
type V7Model = {
|
|
214
325
|
readonly nodes: readonly NodeType[];
|
|
326
|
+
/** Schema-level `extend schema @authentication(…)`: applies to every operation on every type. */
|
|
327
|
+
readonly authentication?: AuthenticationAnnotation;
|
|
328
|
+
/**
|
|
329
|
+
* `@jwtClaim(path)` of the `@jwt` type: field name → dotted path in the JWT payload. Like v7, the
|
|
330
|
+
* mapping is applied to tokens the library verified, not to a decoded `jwt` passed in the context.
|
|
331
|
+
*/
|
|
332
|
+
readonly jwtClaims: ReadonlyMap<string, string>;
|
|
215
333
|
readonly properties: ReadonlyMap<string, PropertiesType>;
|
|
216
334
|
readonly enums: ReadonlyMap<string, EnumType>;
|
|
335
|
+
/** `@cypher` fields of `type Query` / `type Mutation`. */
|
|
336
|
+
readonly query: CypherRootType;
|
|
337
|
+
readonly mutation: CypherRootType;
|
|
217
338
|
node(name: string): NodeType;
|
|
218
339
|
};
|
|
219
340
|
/** The type definitions use a feature `@cyphra/graphql` cannot serve yet. */
|
|
@@ -256,6 +377,13 @@ declare function buildV7Schema(model: V7Model): GraphQLSchema;
|
|
|
256
377
|
* the last / first values ordered by `size(…)` descending; `sum` of an empty set is `0`, the other
|
|
257
378
|
* aggregates are `null`. Int `average` is a Float, BigInt values (including `average`) are strings.
|
|
258
379
|
*
|
|
380
|
+
* Authorization (v7 7.6): the READ `filter` rules of the type (and of the selected fields) are part
|
|
381
|
+
* of the `WHERE` of every node selection, root or nested, and of connection `totalCount`; connection
|
|
382
|
+
* `aggregate` selections use the AGGREGATE rules instead. When READ (AGGREGATE) `validate` rules fail
|
|
383
|
+
* for one node matching the selection's filters (before pagination, like v7), the selection is
|
|
384
|
+
* replaced by a {@link FORBIDDEN_KEY} marker and the field fails with `Forbidden`: the projection of
|
|
385
|
+
* a node that is not allowed is never returned by the database.
|
|
386
|
+
*
|
|
259
387
|
* @packageDocumentation
|
|
260
388
|
*/
|
|
261
389
|
|
|
@@ -272,6 +400,13 @@ declare function cursorToOffset(cursor: unknown): number | undefined;
|
|
|
272
400
|
type MakeSchemaOptions = ExecutorOptions & {
|
|
273
401
|
/** v7 type definitions (`@node`, `@relationship`, …). */
|
|
274
402
|
typeDefs: string;
|
|
403
|
+
/**
|
|
404
|
+
* v7 `features`. `authorization` configures JWT verification for `@authentication` /
|
|
405
|
+
* `@authorization`: the request's `context.token` (`Bearer <jwt>`) is verified with `key` (a
|
|
406
|
+
* secret, a JWKS `{ url }`, or a function of the context returning one). Without it, only a
|
|
407
|
+
* decoded `context.jwt` (trusted as-is) authenticates requests.
|
|
408
|
+
*/
|
|
409
|
+
features?: Features;
|
|
275
410
|
};
|
|
276
411
|
/**
|
|
277
412
|
* Build the GraphQL schema `@neo4j/graphql` v7 generates for `typeDefs`, with resolvers that run on
|
|
@@ -279,9 +414,11 @@ type MakeSchemaOptions = ExecutorOptions & {
|
|
|
279
414
|
*
|
|
280
415
|
* Today: the full v7 schema (SDL identical to v7), the read API (list and connection queries,
|
|
281
416
|
* filters, sorting, offset and cursor pagination, nested relationships and connections with edge
|
|
282
|
-
* properties, connection `aggregate` selections and aggregation filters)
|
|
283
|
-
* update, delete with every nested operation and `info` counters)
|
|
284
|
-
* `@
|
|
417
|
+
* properties, connection `aggregate` selections and aggregation filters), mutations (create,
|
|
418
|
+
* update, delete with every nested operation and `info` counters) and `@authentication` /
|
|
419
|
+
* `@authorization` (compiled into each statement; JWTs verified with `features.authorization`),
|
|
420
|
+
* `@cypher` fields (on node types, relationship properties, `Query` and `Mutation`; sortable and
|
|
421
|
+
* filterable like v7) and `@fulltext` queries (on indexes the application creates).
|
|
285
422
|
*
|
|
286
423
|
* @example
|
|
287
424
|
* ```ts
|
|
@@ -291,11 +428,15 @@ type MakeSchemaOptions = ExecutorOptions & {
|
|
|
291
428
|
*/
|
|
292
429
|
declare function makeSchema(options: MakeSchemaOptions): GraphQLSchema;
|
|
293
430
|
/**
|
|
294
|
-
* The GraphQL `contextValue` for a request
|
|
295
|
-
*
|
|
431
|
+
* The GraphQL `contextValue` for a request, as v7 reads it: `token` is the `Authorization` header
|
|
432
|
+
* (`Bearer <jwt>`, verified with `features.authorization`), `jwt` a payload the server already
|
|
433
|
+
* verified (trusted as-is, takes precedence over `token`). Other keys are kept for
|
|
434
|
+
* `$context.<path>` references in rules.
|
|
296
435
|
*/
|
|
297
436
|
declare function contextFor(opts?: {
|
|
298
437
|
jwt?: Record<string, unknown>;
|
|
438
|
+
token?: string;
|
|
439
|
+
[key: string]: unknown;
|
|
299
440
|
}): Record<string, unknown>;
|
|
300
441
|
/**
|
|
301
442
|
* The Cyphra schema for the same type definitions (through `convertGraphQLTypeDefs`, the converter
|
|
@@ -308,6 +449,9 @@ declare function cyphraSchema(typeDefs: string): {
|
|
|
308
449
|
issues: readonly ImportIssue[];
|
|
309
450
|
};
|
|
310
451
|
|
|
452
|
+
type v7_AuthorizationFeature = AuthorizationFeature;
|
|
453
|
+
type v7_Features = Features;
|
|
454
|
+
type v7_JwtKey = JwtKey;
|
|
311
455
|
type v7_MakeSchemaOptions = MakeSchemaOptions;
|
|
312
456
|
type v7_UnsupportedTypeDefsError = UnsupportedTypeDefsError;
|
|
313
457
|
declare const v7_UnsupportedTypeDefsError: typeof UnsupportedTypeDefsError;
|
|
@@ -320,7 +464,7 @@ declare const v7_makeSchema: typeof makeSchema;
|
|
|
320
464
|
declare const v7_offsetToCursor: typeof offsetToCursor;
|
|
321
465
|
declare const v7_readTypeDefs: typeof readTypeDefs;
|
|
322
466
|
declare namespace v7 {
|
|
323
|
-
export { type v7_MakeSchemaOptions as MakeSchemaOptions, v7_UnsupportedTypeDefsError as UnsupportedTypeDefsError, type v7_V7Model as V7Model, v7_buildV7Schema as buildV7Schema, v7_contextFor as contextFor, v7_cursorToOffset as cursorToOffset, v7_cyphraSchema as cyphraSchema, v7_makeSchema as makeSchema, v7_offsetToCursor as offsetToCursor, v7_readTypeDefs as readTypeDefs };
|
|
467
|
+
export { type v7_AuthorizationFeature as AuthorizationFeature, type v7_Features as Features, type v7_JwtKey as JwtKey, type v7_MakeSchemaOptions as MakeSchemaOptions, v7_UnsupportedTypeDefsError as UnsupportedTypeDefsError, type v7_V7Model as V7Model, v7_buildV7Schema as buildV7Schema, v7_contextFor as contextFor, v7_cursorToOffset as cursorToOffset, v7_cyphraSchema as cyphraSchema, v7_makeSchema as makeSchema, v7_offsetToCursor as offsetToCursor, v7_readTypeDefs as readTypeDefs };
|
|
324
468
|
}
|
|
325
469
|
|
|
326
470
|
/**
|
|
@@ -336,4 +480,4 @@ declare const compat: {
|
|
|
336
480
|
readonly v7: typeof v7;
|
|
337
481
|
};
|
|
338
482
|
|
|
339
|
-
export { GraphQLImportError, type GraphQLImportResult, type GraphQLSource, type ImportIssue, type ImportSeverity, type MakeSchemaOptions, UnsupportedTypeDefsError, compat, convertGraphQLTypeDefs, formatImportReport, mergeImportedSchema, printImportedSchema };
|
|
483
|
+
export { type AuthorizationFeature, type Features, GraphQLImportError, type GraphQLImportResult, type GraphQLSource, type ImportIssue, type ImportSeverity, type JwtKey, type MakeSchemaOptions, UnsupportedTypeDefsError, compat, convertGraphQLTypeDefs, formatImportReport, mergeImportedSchema, printImportedSchema };
|